File Management APIs

Comprehensive file management functionality for selecting files and opening them with external applications in universal apps.

File Management APIs

Comprehensive file management functionality for selecting files and opening them with external applications in universal apps.

🔄 Common Interface

All hooks now follow a standardized interface with execute() as the primary function,data for results, loading for state tracking, and built-in error handling.

useFilePicker() Hook

File selection with MIME type filtering, standardized progress tracking, and comprehensive error handling.

Property	Input	Output	Description
data	`-`	`object \| null`	Selected file data with fileSrc, fileName, size, mimeType, transport, source
loading	`-`	`boolean`	Loading state during file selection operation
error	`-`	`object \| null`	Standardized error object with code, category, message, details, and recovery info
progress	`-`	`object \| null`	Progress tracking with state, phase, message, and transport info
isWeb	`-`	`boolean`	Environment detection flag for web context
isNative	`-`	`boolean`	Environment detection flag for native app context
execute	`mimeType?: string`	`void`	Primary function to open file picker. Optional MIME type parameter for filtering (e.g., "image/*", "application/pdf"). See MIME Types Reference for complete list.
clear	`-`	`void`	Clear selected file data and reset all states
clearError	`-`	`void`	Clear error state only, keeping file data intact

useIntent() Hook

Open files with external applications using standardized interface with Android intents and iOS document interaction support.

Property	Input	Output	Description
data	`-`	`object \| null`	Result data from intent operation including success status
loading	`-`	`boolean`	Loading state during intent processing
error	`-`	`object \| null`	Standardized error object with recovery information
progress	`-`	`object \| null`	Progress tracking during intent operation
isWeb	`-`	`boolean`	Environment detection flag for web context
isNative	`-`	`boolean`	Environment detection flag for native app context
execute	`fileUrl: string, mimeType?: string`	`void`	Primary function to open file with external app. Requires file URL, optional MIME type for better app matching. See MIME Types Reference for complete list.
clear	`-`	`void`	Clear intent data and reset all states
clearError	`-`	`void`	Clear error state only

📁 File Management Example

Select files with MIME type filtering and open them with external applications

FileManagementDemo.js

1import React from 'react';
2import { useFilePicker } from "catalyst-core/hooks";
3
4function FileManagementApp() {
5  const { 
6    data: fileData, 
7    execute: executeFilePicker
8  } = useFilePicker();
9
10  return (
11    <div style={{ padding: '20px', maxWidth: '600px' }}>
12      <h2>📁 File Management Demo</h2>
13      
14      {/* File Picker Section */}
15      <div style={{ marginBottom: '30px', padding: '15px', backgroundColor: '#f9f9f9', borderRadius: '8px' }}>
16        <h3>📂 File Picker</h3>
17        
18        <div style={{ marginBottom: '15px' }}>
19          <button 
20            onClick={() => executeFilePicker('image/*')} 
21            
22            style={{ padding: '10px 15px', marginRight: '10px', fontSize: '14px' }}
23          >
24            '📁 Pick Image'
25          </button>
26          
27          <button 
28            onClick={() => executeFilePicker('application/pdf')} 
29            
30            style={{ padding: '10px 15px', marginRight: '10px', fontSize: '14px' }}
31          >
32            '📄 Pick PDF'
33          </button>
34          
35          <button 
36            onClick={() => executeFilePicker()} 
37            
38            style={{ padding: '10px 15px', fontSize: '14px' }}
39          >
40            '📋 Pick Any File'
41          </button>
42        </div>
43
44        {fileData && (
45          <div style={{ 
46            padding: '10px', 
47            backgroundColor: '#e8f5e8', 
48            borderRadius: '4px',
49            marginBottom: '10px'
50          }}>
51            <p><strong>Selected File:</strong></p>
52            <p>📄 Name: {fileData.fileName}</p>
53            <p>📏 Size: {(fileData.size / 1024).toFixed(2)} KB</p>
54            <p>🔗 Type: {fileData.mimeType || 'Unknown'}</p>
55            <p>📏 Transport: {fileData.transport}</p>
56            
57          </div>
58        )}
59      </div>
60    </div>
61  );
62}
63
64export default FileManagementApp;

Platform & Device Behavior

File management API behavior varies across different platforms and device types. See detailed breakdown below.

Platform	Status	Behavior	Notes
🤖 Android Emulator	`✅ Supported`	File picker works with emulator file system. File intents open with available apps.	Uses Android Virtual Device file system and app intents
🤖 Android Physical	`✅ Supported`	Full file picker functionality with device storage. File intents use installed apps.	Requires storage permissions. Works with all installed apps.
🍎 iOS Simulator	`⏳ Coming Soon`	iOS file picker and intent functionality currently in development.	File management features not yet implemented for iOS Simulator
🍎 iOS Physical	`⏳ Coming Soon`	iOS file picker and intent functionality currently in development.	Native iOS Files app integration planned for future release
🌐 Web Browser	`🔄 Fallback`	Browser file picker for uploads. Limited file opening capabilities.	Browser security restrictions apply. Limited MIME type support.

Important Notes

Platform Support: Works on both iOS and Android native apps
MIME Types: Use specific MIME types for better file filtering (e.g., "image/*", "application/pdf")
File Access: Selected files provide URI for further processing or opening with intents
Error Handling: Both hooks include comprehensive error handling for failed operations
State Management: Processing states help provide user feedback during operations
Web Fallback: Returns safe defaults when running in web mode

File Management APIs